<!DOCTYPE html>
<html>
<head><title>dec64_string</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<style>
@import url(http://fonts.googleapis.com/css?family=Cousine:700);
@import url(http://fonts.googleapis.com/css?family=Inika:400,700);
body {
    background-color: cornsilk;
    border-left: 1em solid indianred;
    font-family: 'Inika', serif;
    margin-left: 1em;
    max-width: 50em;
    padding: 10%;
}

code, pre {
    font-family: "Courier New", Courier, mono;
    font-size: 100%;
	font-weight: normal;
}

pre {
    padding-left: 2em;
    padding-right: 1em;
    padding-bottom: 0.25em;
    padding-top: 0.25em;
	text-align: left;
}

a {  /* link */
    font-size: 100%;
    font-variant: normal;
    font-weight: normal;
    text-decoration: none;
}

a:link {
    color: midnightblue;
}
a:visited {
    color: purple;
}
a:hover {
	border-bottom: 1pt solid blue;
    color: blue;
}
a:active {
	border-bottom: 1pt dotted red;
    color: red;
}

table {
	margin-top: -1em;
}

td {
    background-color: navajowhite;
    border: 2pt solid black;
    text-align: center;
}

th {
    background-color: inherit;
    border: 0;
	font-weight: lighter;
	padding-left: 3pt;
	padding-right: 3pt;
	text-align: center;
}

.dec64, h1, h2 {
    font-family: 'Cousine', sans-serif;
};

</style>
</head>

<body>
<a href="http://www.DEC64.com/"><img src="dec64.png" alt="DEC64" width="398" height="103" border="0"></a>
<h1>dec64_string.c</h1>
<p>One of the most difficult problems in floating-point systems is the
    conversion of numbers to text. This conversion is important because humans
    generally cannot use binary representations, and there are not simple, exact
    transformations between familiar decimal representations and binary
    floating-point. It can be difficult and expensive to find representations
    that are accurate, minimal, and unsurprising. </p><br>
<table>
  <tr>
    <th scope="col">&nbsp;</th>
    <th align="center" scope="col"><code>0.1 + 0.2</code></th>
    <th align="center" scope="col"><code>10 / 3</code></th>
    <th align="center" scope="col"><code>10.1 - 9.93</code></th>
  </tr>
  <tr>
    <th>IEEE754</th>
    <td><pre>0.30000000000000004</pre></td>
    <td><pre>3.3333333333333335</pre></td>
    <td><pre>0.16999999999999993</pre></td>
  </tr>
  <tr>
    <th><span class=dec64>DEC64</span></th>
    <td align="left"><pre>0.3</pre></td>
    <td><pre>3.3333333333333333</pre></td>
    <td align="left"><pre>0.17</pre></td>
  </tr>
</table>
<p>One of <span class=dec64>DEC64</span>'s advantages is that it easily and
    accurately converts  to decimal representations, requiring only slightly
    more effort than the conversion of integers.</p>
<p><a href="https://github.com/douglascrockford/DEC64/blob/master/dec64_string.c">
    dec64_string.c</a> contains functions for converting
    <span class=dec64>DEC64</span> numbers to strings and back again.
    <a href="https://github.com/douglascrockford/DEC64/blob/master/dec64_text.h">
    dec64_string.h</a> includes C function prototypes for these functions:</p>
<pre>dec64 <a href="#dec64_from_string"><b>dec64_from_string</b></a>(
    dec64_string_state state,
    dec64_string_char string[]
)</pre>

<pre>dec64_string_state <a href="#dec64_string_begin"><b>dec64_string_begin</b></a>()</pre>

<pre>dec64_string_char <a href="#dec64_string_decimal_point"><b>dec64_string_decimal_point</b></a>(
    dec64_string_state state,
    dec64_string_char decimal_point
)</pre>

<pre>void <a href="#dec64_string_end"><b>dec64_string_end</b></a>(
    dec64_string_state state
)</pre>

<pre>void <a href="#dec64_string_engineering"><b>dec64_string_engineering</b></a>(
    dec64_string_state state
)</pre>

<pre>int <a href="#dec64_string_places"><b>dec64_string_places</b></a>(
    dec64_string_state state,
    dec64_string_char places
)</pre>

<pre>void <a href="#dec64_string_scientific"><b>dec64_string_scientific</b></a>(
    dec64_string_state state
)</pre>

<pre>int <a href="#dec64_string_separation"><b>dec64_string_separation</b></a>(
    dec64_string_state state,
    int separation
)</pre>

<pre>dec64_string_char <a href="#dec64_string_separator"><b>dec64_string_separator</b></a>(
    dec64_string_state state,
    dec64_string_char separator
)</pre>

<pre>void <a href="#dec64_string_standard"><b>dec64_string_standard</b></a>(
    dec64_string_state state
)</pre>

<pre>int <a href="#dec64_to_string"><b>dec64_to_string</b></a>(
    dec64_string_state state,
    dec64 number,
    dec64_string_char string[]
)</pre>

<p>Two types are provided:</p>
<ul>
  <li><code><b>dec64_string_char</b></code></li>
  <li><code>  <b>dec64_string_state</b></code></li>
</ul>
<h2 id="state">String State</h2>
<p>There functions are reentrant and thread safe. This is accomplished by use of
    a state object that is created by
    <code><a href="#dec64_string_begin">dec64_string_begin</a></code> and
    destroyed by <code><a href="#dec64_string_end">dec64_string_end</a></code>.
    All of these functions require a state object as the first argument. The
    state argument allows for customizing the conversions. Do not attempt to
    modify the string state object directly. Use the provided functions instead.
    State objects are reusable.</p>
<p>The state object contains the output mode: standard, scientific, or engineering.</p>
<h2 id="creation">Creation</h2>
<pre>dec64_string_state <a id="dec64_string_begin"><b>dec64_string_begin</b></a>()</pre>
<p><code>dec64_string_begin</code> creates a state object. The object should be
    passed to all of the other functions.</p>
<h2 id="destruction">Destruction</h2>
<pre>void <a id="dec64_string_end"><b>dec64_string_end</b></a>(
    dec64_string_state state
)</pre>
<p><code>dec64_string_end</code> destroys and deallocates a state object.</p>
<h2 id="configuration">Configuration</h2>
<p>The following functions configure or customize a state object.</p>
<pre>void <a id="dec64_string_standard"><b>dec64_string_standard</b></a>(
    dec64_string_state state
)</pre>
<p>Put <code><a href="#dec64_to_string">dec64_to_string</a></code> into standard
    mode. Separators can be inserted between some digits if requested. If the
    number might be too long, then scientific mode might be used instead.</p>
<p>Standard mode is the default.</p>
<pre>void <a id="dec64_string_scientific"><b>dec64_string_scientific</b></a>(
    dec64_string_state state
)</pre>
<p>Put <code><a href="#dec64_to_string">dec64_to_string</a></code> into scientific mode, in which the coefficient is
    displayed with one digit before the decimal point, and an exponent prefixed
    with '<code>e</code>' is appended if necessary.</p>
<pre>void <a id="dec64_string_engineering"><b>dec64_string_engineering</b></a>(
    dec64_string_state state
)</pre>
<p>Put <a href="#dec64_to_string"><code>dec64_to_string</code></a> into
    engineering mode, which is like scientific mode  except that the exponent is
    constrained to be a multiple of 3. There can be up to three digits before
    the decimal point.</p>
<pre>dec64_string_char <a id="dec64_string_decimal_point"><b>dec64_string_decimal_point</b></a>(
    dec64_string_state state,
    dec64_string_char decimal_point
)</pre>
<p>Specify the decimal point character. This is used by both
    <code><a href="#dec64_to_string">dec64_to_string</a></code> and
    <code><a href="#dec64_from_string">dec64_from_string</a></code>.
    The default is '<code>.</code>'. If it is '<code>\0</code>', then the
    decimal point will be suppressed.</p>
<p> It returns the previous value.</p>
<pre>int <a id="dec64_string_places"><b>dec64_string_places</b></a>(
    dec64_string_state state,
    dec64_string_char places
)</pre>
<p>Specify the minimum number of decimal places output by
    <a href="#dec64_to_string"><code>dec64_to_string</code></a> in standard
    mode. This is commonly used to format money values. The default is
    <code>0</code>.</p>
<p> It returns the previous value.</p>
<pre>dec64_string_char <a id="dec64_string_separator"><b>dec64_string_separator</b></a>(
    dec64_string_state state,
    dec64_string_char separator
)</pre>
<p>Specify the separation character, which is used by
    <code><a href="#dec64_to_string">dec64_to_string</a></code> in standard
    mode to improve the readability of digits before the decimal point. Typical
    values include</p>
<blockquote>
'<code>,</code>'&nbsp;&nbsp;&nbsp;&nbsp;'<code> </code>'&nbsp;&nbsp;&nbsp;&nbsp;'<code>_</code>'&nbsp;&nbsp;&nbsp;&nbsp;'<code>.</code>'&nbsp;&nbsp;&nbsp;&nbsp;'<code>\0</code>' </p>
</blockquote>
<p>If it is '<code>\0</code>', then separation will be
  suppressed. The default is '<code>\0</code>'.</p>
<p><code><a href="#dec64_from_string">dec64_from_string</a></code> will ignore
    this character.</p>
<p>It returns the previous value.</p>
<pre>int <a id="dec64_string_separation"><b>dec64_string_separation</b></a>(
    dec64_string_state state,
    int separation
)</pre>
<p>Specify the number of digits output between separators by
    <code><a href="#dec64_to_string">dec64_to_string</a></code> in standard
    mode. If separation is <code>1</code> or less, then separation is
    suppressed. The default is <code>3</code>.</p>
<p> It returns the previous value.</p>

<h2 id="action">Action</h2>

<pre>dec64 <a id="dec64_from_string"><b>dec64_from_string</b></a>(
    dec64_string_state state,
    dec64_string_char string[]
)</pre>
<p><code>dec64_from_string</code> converts a zero-delimited string into a <code>dec64</code>. Separator
    characters will be ignored. If conversion is not possible for any reason,
    the result will be <code>DEC64_NAN</code>.</p>
<pre>int <a id="dec64_to_string"><b>dec64_to_string</b></a>(
    dec64_string_state state,
    dec64 number,
    dec64_string_char string[]
)</pre>
<p><code>dec64_to_string</code> converts a <code>dec64</code> number into a
    string. The caller provides the memory into which to deposit the string. The
    provided string must have sufficient capacity to hold 32 characters. It
    returns the number of characters actually deposited in the string (not
    including the trailing '<code>\0</code>'). If the number is <var>nan</var>,
    then it returns <code>0</code> indicating an empty string. If
    <code>NULL</code> is passed in as the string, then no characters will be
    deposited, but a character count will be returned.</p>
<p>In standard mode, the number will be formatted conventionally unless it
  would require more than 17 digits, which would be due to excessive
  trailing zeros or zeros immediately after the decimal point. In that
  case scientific notation will be used instead.</p>
<h2 id="examples">Examples</h2>
<table>
  <tr>
    <td><pre>dec64_string_state state = dec64_string_begin();
dec64_to_string(state, dec64_new(10, -128), string);</pre></td>
    <td><pre>&quot;1e-127&quot;</pre></td>
  </tr>
  <tr>
    <td><pre>dec64_to_string(state, dec64_new(1024, 0), string);</pre></td>
    <td><pre>&quot;1024&quot;</pre></td>
  </tr>
  <tr>
    <td><pre>dec64_separator(state, ',');
dec64_to_string(state, dec64_new(1024, 0), string);</pre></td>
    <td><pre>&quot;1,024&quot;</pre></td>
  </tr>
  <tr>
    <td><pre>dec64_separator(state, ' ');
dec64_to_string(state, dec64_new(1024, 0), string);</pre></td>
    <td><pre>&quot;1 024&quot;</pre></td>
  </tr>
  <tr>
    <td><pre>dec64_places(state, 4);
dec64_to_string(state, dec64_new(1024, 0), string);</pre></td>
    <td><pre>&quot;1 024.0000&quot;</pre></td>
  </tr>
  <tr>
    <td><pre>dec64_scientific(state);
dec64_to_string(state, dec64_new(1024, 0), string);</pre></td>
    <td><pre>&quot;1.024e3&quot;</pre></td>
  </tr>
  <tr>
    <td><pre>dec64_from_string(state, &quot;1 024.0000&quot;)</pre></td>
    <td><pre>1024</pre></td>
  </tr>
  <tr>
    <td><pre>dec64_from_string(state, &quot;1,024.0000&quot;)</pre></td>
    <td><pre>DEC64_NAN</pre></td>
  </tr>
  <tr>
    <td><pre>dec64_separator(state, ',');
dec64_from_string(state, &quot;1,024.0000&quot;)</pre></td>
    <td><pre>1024</pre></td>
  </tr>
  <tr>
    <td><pre>dec64_string_end();</pre></td>
    <td><pre>&nbsp;</pre></td>
  </tr>
</table>
</body>
</html>
